home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 25
/
Cream of the Crop 25.iso
/
bbs
/
inf121d.zip
/
dev.doc
< prev
next >
Wrap
Text File
|
1996-11-02
|
28KB
|
721 lines
______ ___________________ ______
> |____________| InfoMail/386 1.20 |____________| <
~~||~~| Centurion |~~~~~~~~~~~~~~~~~~~| 2:2502/666 |~~||~~
|| ~~~~~~~~~~~~ ~~~~~~~~~~~~ ||
|| ||
|| ||
|| ||
|| CENTURION ||
|| ||
|| ||
|| -*- ||
|| ||
|| ||
|| InfoMail/386 1.20 ||
|| ||
|| A Document Server for Fidonet Systems ||
|| ||
|| Copyright (C) Damian Walker 1996 ||
|| ||
|| ||
|| -*- ||
|| ||
|| ||
|| DEVELOPER'S GUIDE ||
|| ||
|| ||
|| _____ ||
|| (____() ||
|| / / ||
|| / / ||
|| (____() ||
|| _______ ||
|| (_)|||(_) ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| ||||| ||
|| /~~~~~\ ||
|| ~~~~~~~ ||
|| ||
|| ||
|| ||
|| ||
|| ____________ ____________ ||
__||__| Copyright |___________________| 1996 |__||__
> |~~~~~~~~~~~~| (C) Damian Walker |~~~~~~~~~~~~| <
~~~~~~ ~~~~~~~~~~~~~~~~~~~ ~~~~~~
1. INTRODUCTION
The developer's guide has been written with other software
authors in mind; it is primarily designed for people who want to
write programs to interface with InfoMail/386 1.20.
It is laid out in the form of a reference guide, with a section
for the configuration file, and a section for the document list
files.
Information relevant to users can be found in the User and
Reference Guides (USER.DOC and REF.DOC), a full table of
contents for this and the other manuals is in the file
CONTENTS.DOC, and a full index is given as the file INDEX.DOC.
Introduction D- 2
2. THE CONFIGURATION FILE
There is only one file for the general configuration, this being
INFOMAIL.CFG. The file's general format is as follows:
┌───────┬───────────────────────────────┬───────┬───────┬──────┐
│HEADER │CONFIGURATION │AKA REC│AKA REC│... │
└───────┴───────────────────────────────┴───────┴───────┴──────┘
The header is available for verification of the file. It is
advisable that the header be read and verified before
progressing to read the rest of the file; if the header is
invalid then the rest of the file is likely to contain nonsense.
The header section is 8 bytes long, and contains the following
characters:
┌───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┐
│ I │ N │ F │ 1 │ 2 │ 0 │ S │ <NUL> │
│ 73 │ 78 │ 70 │ 49 │ 50 │ 48 │ 83 │ 0 │
│ 49h │ 4Eh │ 46h │ 31h │ 32h │ 30h │ 53h │ 00h │
└───────┴───────┴───────┴───────┴───────┴───────┴───────┴───────┘
The configuration section has the following structure, presented
here as a language-independent table:
The Configuration File D- 3
┌──────────────────────────────────────────────────────────────┐
│MAIN CONFIGURATION TABLE │
├───────┬───────┬──────────────────────────────────────────────┤
│NETMAIL│char/64│netmail directory │
│LOGFILE│char/64│path and name of log file │
│FLAGS │int/2 │various flags: │
│ │ │bit 0 active │
│ │ │bit 1 kill inbound requests │
│ │ │bit 2 kill inbound updates │
│ │ │bit 3 kill inbound searches │
│ │ │bit 4 kill outbound responses │
│REQUEST│char/36│user name for requests │
│UPDATE │char/36│user name for updates │
│SEARCH │char/36│user name for searches │
│HEADER │char/64│path and name of global header │
│FOOTER │char/64│path and name of global footer │
│DOCLIST│char/64│path and name of doc list template │
│NOFILE │char/64│file name of file error template │
│INACTIV│char/64│file name of 'inactive' template │
│ACCEPT │char/64│name of update accepted template │
│REJECT │char/64│name of 'rejected' template │
│RESULTS│char/64│name of search results template │
│SPLIT │int/2 │maximum message size │
├───────┴───────┴──────────────────────────────────────────────┤
│AKA RECORD │
├───────┬───────┬──────────────────────────────────────────────┤
│ZONE │int/2 │fidonet zone │
│NET │int/2 │net number │
│NODE │int/2 │node number │
│POINT │int/2 │point address │
└───────┴───────┴──────────────────────────────────────────────┘
The characters before each '/' refer to the type, and the number
after it refers to the size in bytes. Thus int/2 is a 2-byte
integer, and char/64 is a 64-byte character string. Since
InfoMail was written in C, all the character variables (i.e. all
the char/36s and char/64s) are null terminated. All the int/2s
are in low-byte/high-byte form, as is the normal Intel practice.
These fields are all verified at the time they are entered in
the configuration editor. This means that if you are planning
to write to the configuration file yourself, you need to make
sure that you make the same checks as InfoMail itself. These
checks are described in the following sections.
2.1. The NETMAIL field
This field is a 64-character ASCIIZ string, containing the
netmail directory. InfoMail requires that there is a
terminating backslash on this field, unless it is a simple drive
letter (in which case the colon is required). Failure to add
this backslash to the NETMAIL field means that InfoMail will
fail to find netmail messages, possibly causing an error:
The Configuration File D- 4
! No netmails to read
InfoMail itself converts the name to upper case, and converts
any Unix-style slashes (/) entered by the user into DOS
backslashes (\).
InfoMail will run happily with either slash in the netmail
field, and will also accept pathnames in upper or lower case,
but if the NETMAIL field contains lower case letters or a Unix
slash, this will be altered next time the user edits the NETMAIL
field in the configuration editor. Thus it may be aesthetically
more pleasing to format the names as InfoMail does, before
writing them.
2.2. The LOGFILE field
As mentioned in the user guide, this field is mandatory. A full
valid path and filename must be written to this field. If a
valid DOS filename is not present, InfoMail will refuse to run.
Filename formatting is as per the netmail field. InfoMail
converts Unix slashes to DOS backslashes and converts the
filename to upper case when the field is edited in the
configuration editor, but it will run with lower case filenames
and Unix slashes.
2.3. The FLAGS field
This is a compound binary field, containing five flags and room
for eleven more. The eleven unused flags may currently be used
by third-party utilities, but as InfoMail gets updated and
expanded some of these may be used by the program itself.
It is recommended that third-party utilities implementing their
own flags in the INFOMAIL.CFG file restrict themselves to using
bits 12 to 15 of the FLAGS field. Bear in mind however, that
use of your utility at a user's installation may preclude the
use of another utility which uses the same flag field, so unless
there is very little data to be stored by your utility, it is
recommended that you maintain your own configuration file for
any values it may need over and above those already used by
InfoMail.
Bit 0 of this field is the active flag. Setting it to 1 (the
normal value) indicates that the installation is active.
Bit 1 of this field is the Kill Inbound Requests flag, 2
indicates 'Yes' and 0 indicates 'No'.
Bit 2 of this field is the Kill Inbound Updates flag, 4 meaning
'Yes' and 0 meaning 'No'.
Bit 3 of this field is the Kill Inbound Searches flag, 8 meaning
'Yes' and 0 meaning 'No'.
The Configuration File D- 5
Bit 4 of this field is the Kill Outbound Responses flag, 16
meaning 'Yes' and 0 meaning 'No'.
Since these are binary 2-state fields, and all combinations are
valid, no validation is required before writing their value.
See the reference guide for further details about their effect
upon InfoMail's behaviour.
2.4. The REQUEST field
This is a simple ASCIIZ character string showing the name which,
when found in the 'To:' field of a message, tells InfoMail that
the message is a document request. No validation is necessary,
other than checks for string length and zero termination in
languages which do not use fixed length/zero terminated strings.
InfoMail checks for this name in inbound messages before
checking for the update and search names (see next 2 sections),
so document requests are not affected by having identical values
in the REQUEST field and the UPDATE (and/or SEARCH) fields.
2.5. The UPDATE field
This is a simple ASCIIZ character string showing the name which,
when found in the 'To:' field of a message, tells InfoMail that
the message is a document update.
Apart from checks for string length and zero termination, it may
be useful to verify that the value of this field is not
identical to that of the REQUEST field. Identical values in
these fields would not cause problems when running InfoMail,
other than preventing document updates from being made.
2.6. The SEARCH field
This is a simple ASCIIZ character string showing the name which,
when found in the 'To:' field of a message, tells InfoMail that
the message is a document search request.
Apart from checks for string length and zero termination, it may
be useful to verify that the value of this field is not
identical to that of the REQUEST or UKDATE fields. Identical
values in these fields would not cause problems when running
InfoMail, other than preventing document searches from being
requested.
2.7. The HEADER field
This is a simple ASCIIZ string containing a filename. The
formatting of this filename are as for the LOGFILE field. If
the filename is invalid, InfoMail includes no header in outgoing
messages.
The Configuration File D- 6
2.8. The FOOTER field
This is a simple ASCIIZ string containing a filename. The
formatting of this filename is as for the LOGFILE field. If the
filename is invalid, InfoMail includes no footer in outgoing
messages.
2.9. The DOCLIST field
This is a simple ASCIIZ string containing a filename. The
formatting of this filename is as for the LOGFILE field. If the
filename is invalid, the standard format is used for document
lists.
2.10. The NOFILE field
This is a simple ASCIIZ string containing a filename. The
formatting of this filename is as for the LOGFILE field. If the
filename is invalid, the standard format is used for file
errors.
2.11. The INACTIV field
This is a simple ASCIIZ string containing a filename. The
formatting of this filename is as for the LOGFILE field. If the
filename is invalid, the standard format is used for document
inactive errors.
2.12. The ACCEPT field
This is a simple ASCIIZ string containing a filename. The
formatting of this filename is as for the LOGFILE field. If the
filename is invalid, the standard format is used for update
accepted responses.
2.13. The REJECT field
This is a simple ASCIIZ string containing a filename. The
formatting of this filename is as for the LOGFILE field. If the
filename is invalid, the standard format is used for reject
messages.
2.14. The RESULTS field
This is a simple ASCIIZ string containing a filename. The
formatting of this filename is as for the LOGFILE field. If the
filename is invalid, the standard format is used for search
results.
2.15. The SPLIT field
This is a standard, unsigned 2-byte integer. All possible
values of this field are valid, so no checking is necessary.
The Configuration File D- 7
2.16. The AKA LIST records
InfoMail does not limit the number of these records which can be
added to the end of a configuration file, so the number which
might exist is limited only by disk space.
It does not check for duplicate values on loading these records,
so if duplicate addresses are created this will have a slight
impact on InfoMail's running speed. It is best to check for
duplicate values in your own program, especially when adding
addresses yourself which may already be present.
The list is not sorted in any way, so checks for addresses must
consist of a complete search of all addresses present. InfoMail
does not record the number of addresses present, so the file
size must be recorded or an EOF check made to ensure you don't
read past the end of the file.
All integers are 2-byte signed values, as per the normal Fidonet
standard. All addresses are full 4D-addresses, with a point
value of zero for full node addresses.
The Configuration File D- 8
3. THE DOCUMENT LIST FILES
There are two files used to store the document list,
INFOMAIL.DAT and INFOMAIL.NDX. INFOMAIL.DAT is the main data
file, and INFOMAIL.NDX is the index file. The files have the
following overall format:
┌───────┬───────────────┬───────────────┬──────┐
INFOMAIL.DAT │HEADER │DOCUMENT │DOCUMENT │... │
└───────┴───────────────┴───────────────┴──────┘
┌───────┬───────────────┬───────────────┬──────┐
INFOMAIL.NDX │HEADER │INDEX RECORD │INDEX RECORD │... │
└───────┴───────────────┴───────────────┴──────┘
The header of both files is used to verify their validity, in
case of corruption or copying of other files over the valid
document list. The HEADER section for INFOMAIL.DAT contains the
following characters:
┌───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┐
│ I │ N │ F │ 1 │ 2 │ 0 │ D │ <NUL> │
│ 73 │ 78 │ 70 │ 49 │ 50 │ 48 │ 68 │ 0 │
│ 49h │ 4Eh │ 46h │ 31h │ 32h │ 30h │ 44h │ 00h │
└───────┴───────┴───────┴───────┴───────┴───────┴───────┴───────┘
and the header section of INFOMAIL.NDX contains the following:
┌───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┐
│ I │ N │ F │ 1 │ 2 │ 0 │ X │ <NUL> │
│ 73 │ 78 │ 70 │ 49 │ 50 │ 48 │ 88 │ 0 │
│ 49h │ 4Eh │ 46h │ 31h │ 32h │ 30h │ 58h │ 00h │
└───────┴───────┴───────┴───────┴───────┴───────┴───────┴───────┘
If any other sequence of characters forms the first eight bytes
of either file, it is recommended that you close the files
immediately and terminate the program (or run it without the use
of these files, where possible). Invalid values in these
headers mean that the format of the files may be invalid and may
confuse your program.
The format of a document record in the file INFOMAIL.DAT is
represented in language-independent form in the following table:
The Document List Files D- 9
┌───────┬───────┬──────────────────────────────────────────────┐
│DELETED│int/2 │deleted flag │
│DOCNAME│char/18│document name/tag │
│FLAGS │int/2 │general document flags │
│ │ │bit 0 macros │
│ │ │bit 1 listed │
│ │ │bit 2 smart routing (unused in this version) │
│ │ │bit 3 active │
│SUBJECT│int/72 │subject line │
│ATTR │int/2 │attributes for outgoing messages │
│REQUEST│char/9 │request password │
│UPDATE │char/9 │update password │
│FILE │char/64│primary document text file │
│SECFILE│char/64│secondary document text file │
│COUNTER│int/2 │document access counter │
└───────┴───────┴──────────────────────────────────────────────┘
The format of the index file INFOMAIL.NDX is as follows:
┌───────┬───────┬──────────────────────────────────────────────┐
│DOCNAME│char/18│document name │
│FILEPOS│int/4 │record position in list file │
└───────┴───────┴──────────────────────────────────────────────┘
As with the configuration file, the type description is
'type/size', size being in bytes, and all char values are
null-terminated ASCIIZ strings, and all verifications of these
fields are made while in the document list editor, so developers
writing to these files will have to perform the appropriate
verifications themselves, according to the information in the
following subsections.
3.1. The DELETED field
This field indicates that the document record has been marked as
deleted. Currently any value in this field other than zero is
taken as 'deleted'.
In normal usage, this field should never be set when InfoMail is
not running. The document list editor sets this field to 1 when
records are deleted by the user, and removes all such records
when the user leaves the editor. Also, the field is briefly
used by the netmail scan to mark records NOT matching search
criteria during a document search; after the search results are
sent to the user, all records are marked as undeleted (i.e. a 0
is stored in this field).
Other third-party utilities may make use of the field in a
similar fashion, as long as all records are marked as NOT
deleted (i.e. DELETED = 0) before InfoMail could possibly be
run.
The Document List Files D-10
3.2. The DOCNAME field
This field, in both the index file and the document list file,
contains the document name. Taking InfoMail as it stands, the
name in the document list file itself seems superfluous, but it
may be that third-party utilities create indexes on other fields
for their own use, and thus the document name would be required
in the main file.
Although this field is 18 characters, allowing 17-character
document names, no document name should exceed 16 characters
(plus the terminating NULL). The reason for the extra character
in the file is that the DJGPP compiler word-aligns fields.
3.3. The FLAGS field
This field contains various Yes/No type information about each
individual document. Developers implementing their own document
flags in this field should restrict themselves to using bits 12
to 15, as InfoMail may make use of flags 4 to 11 in future
releases.
Bit 0 is the Macros flag, a value of 1 meaning 'Yes' and a value
of 0 meaning 'No'.
Bit 1 is the Listed flag, a value of 2 meaning 'Yes' and a value
of 0 meaning 'No'.
Bit 2 is the Smart Routing flag, which is currently unused.
This flag should be left alone by third-party programs, as it
may be used in future, even for the current release of InfoMail
(by a secondary add-on program).
Bit 3 is the Active flag, a value of 8 meaning 'Yes' and a value
of 0 meaning 'No'.
See the reference guide for more information about the effect of
these flags on the behaviour of the InfoMail program.
3.4. The SUBJECT field
This is a simple ASCIIZ string containing the subject line for
outgoing messages. It is a freeform text field. Although it is
72 characters long, only 64 characters should be used (creating
a maximum subject length of 63 characters). Longer subject
lines will cause InfoMail to crash.
3.5. The ATTR field
This is the attributes field which will be stamped on outgoing
primary messages for this document. Refer to the document FTS-1
for details on the exact meaning of these flags. Although the
Pvt and Local flags do not appear in the document editor, they
will always be set in the document list file.
The Document List Files D-11
If your program modifies the values of attributes not directly
supported by the document list editor, InfoMail will not change
these. It is therefore recommended that you leave the Pvt and
Local flags set.
3.6. The REQUEST field
This is a request password, and is a freeform ASCIIZ string.
InfoMail does not do any case conversion of this value in the
file, even though the password comparison is case insensitive.
3.7. The UPDATE field
This is an update password, and is a freeform ASCIIZ string.
InfoMail does not do any case conversion of this value in the
file, even though the password comparison is case insensitive.
3.8. The FILE field
This filename field is an ASCIIZ string, its contents following
normal DOS filename conventions. Exact details of formatting
are as for the LOGFILE field in the configuration file, see
section 2.2 for these.
3.9. The SECFILE field
The SECFILE field has the same format and behaviour as the FILE
field described in section 3.8.
3.10. The COUNTER field
This is a 2-byte integer, unsigned. All possible values are
valid, so no checking is necessary.
3.11. Details of the Index File
The index file is sorted in alphabetical/ASCII order, although
the sorting is case insensitive, i.e. the records Acorn, apple,
Banana would appear in that order.
The FILEPOS field is a signed integer pointing to the position
in INFOMAIL.DAT where a particular document lies, that document
being identified in the index file by document name (DOCNAME).
The DOCNAME field in each file should match exactly. The first
byte of the file is position 0.
If a third-party application leaves the index in a mess
(unsorted, or sorted in a case-sensitive order), then InfoMail
will exhibit strange behaviour, often failing to find documents
which are present. If this problem occurs during development,
you should load the document list editor and quit it immediately
(since the final document pack in the editor re-indexes the
file). The INFOMAIL.DAT file is completely unsorted.
The Document List Files D-12
